"""WMS3D系统核心异常模块。

该模块定义了系统中使用的所有自定义异常类，用于：
1. 统一错误处理
2. 提供详细的错误信息
3. 支持API错误响应格式
4. 区分不同类型的错误

所有异常都继承自WMSException基类，确保一致的错误处理机制。
"""

from typing import Any, Dict


class WMSException(Exception):
    """WMS3D系统基础异常类。

    所有自定义异常的基类，提供统一的错误信息结构。
    """

    def __init__(
        self, message: str, error_code: str | None = None, details: dict[str, Any] | None = None
    ):
        """初始化异常。

        Args:
            message (str): 错误消息
            error_code (str | None): 用于API响应的错误代码
            details (Dict[str, Any] | None): 额外的错误详情
        """
        self.message = message
        self.error_code = error_code or "WMS_ERROR"
        self.details = details or {}
        super().__init__(self.message)


class ValidationError(WMSException):
    """验证错误异常。

    用于表示数据验证失败的异常。
    """

    def __init__(
        self, message: str, field: str | None = None, details: dict[str, Any] | None = None
    ):
        """初始化验证错误。

        Args:
            message (str): 错误消息
            field (str | None): 验证失败的字段
            details (Dict[str, Any] | None): 额外的错误详情
        """
        super().__init__(
            message=message,
            error_code="VALIDATION_ERROR",
            details={"field": field, **(details or {})},
        )


class CoordinateOutOfRangeError(ValidationError):
    """坐标超出仓库边界异常。

    当坐标值超出仓库定义的边界范围时抛出。
    """

    def __init__(self, coordinate: str, value: float, min_val: float, max_val: float):
        """初始化坐标错误。

        Args:
            coordinate (str): 坐标名称（x, y, z）
            value (float): 无效的坐标值
            min_val (float): 允许的最小值
            max_val (float): 允许的最大值
        """
        super().__init__(
            message=f"坐标 {coordinate}={value} 超出范围 [{min_val}, {max_val}]",
            field="position",
            details={"coordinate": coordinate, "value": value, "min": min_val, "max": max_val},
        )


class ObjectNotFoundError(WMSException):
    """物品未找到异常。

    当请求的物品不存在时抛出。
    """

    def __init__(self, object_id: str):
        """初始化物品未找到错误。

        Args:
            object_id (str): 未找到的物品ID
        """
        super().__init__(
            message=f"ID为 {object_id} 的物品未找到",
            error_code="OBJECT_NOT_FOUND",
            details={"object_id": object_id},
        )


class LocationNotFoundError(WMSException):
    """库位未找到异常。

    当请求的库位不存在时抛出。
    """

    def __init__(self, location_id: str):
        """初始化库位未找到错误。

        Args:
            location_id (str): 未找到的库位ID
        """
        super().__init__(
            message=f"ID为 {location_id} 的库位未找到",
            error_code="LOCATION_NOT_FOUND",
            details={"location_id": location_id},
        )


class SKUNotFoundError(WMSException):
    """SKU未找到异常。

    当请求的SKU不存在时抛出。
    """

    def __init__(self, sku_id: str):
        """初始化SKU未找到错误。

        Args:
            sku_id (str): 未找到的SKU ID
        """
        super().__init__(
            message=f"ID为 {sku_id} 的SKU未找到",
            error_code="SKU_NOT_FOUND",
            details={"sku_id": sku_id},
        )


class BusinessRuleError(WMSException):
    """业务规则违反异常。

    当业务规则被违反时抛出，如位置验证失败等。
    """

    def __init__(
        self, message: str, rule_name: str | None = None, details: dict[str, Any] | None = None
    ):
        """初始化业务规则错误。

        Args:
            message (str): 错误消息
            rule_name (str | None): 违反的规则名称
            details (Dict[str, Any] | None): 额外的错误详情
        """
        super().__init__(
            message=message,
            error_code="BUSINESS_RULE_VIOLATION",
            details={"rule": rule_name, **(details or {})},
        )


class TrajectoryServiceError(WMSException):
    """轨迹服务异常。

    当轨迹服务操作失败时抛出。
    """

    def __init__(self, message: str, details: dict[str, Any] | None = None):
        """初始化轨迹服务错误。

        Args:
            message (str): 错误消息
            details (Dict[str, Any] | None): 额外的错误详情
        """
        super().__init__(
            message=message,
            error_code="TRAJECTORY_SERVICE_ERROR",
            details=details or {},
        )
